/*
 * 
 *  This file is part of Sourceprojects.org Lycia Copyright 2010 noctarius
 *
 *  Licensed under the Apache License, Version 2.0 (the "License");
 *  you may not use this file except in compliance with the License.
 *  You may obtain a copy of the License at
 *
 *    http://www.apache.org/licenses/LICENSE-2.0
 *
 *  Unless required by applicable law or agreed to in writing, software
 *  distributed under the License is distributed on an "AS IS" BASIS,
 *  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 *  See the License for the specific language governing permissions and
 *  limitations under the License.
 * 
 */
package org.sourceprojects.lycia.io;

import org.sourceprojects.lycia.LyciaParser;
import org.w3c.dom.Document;
import org.xml.sax.InputSource;

/**
 * The interface of reader implementations that Lycia use for parsing structured
 * data to an internal DOM representation.
 * 
 * @author noctarius
 * 
 * @param <B>
 *            Type of ContextObject to use
 * @since 1.9.5
 */
public interface LyciaReader<B> {

	/**
	 * Sets the actual instance of the {@link LyciaParser}
	 * 
	 * @param xmlParser
	 *            actual XmlParser instance
	 */
	void setXmlParser(LyciaParser<B> xmlParser);

	/**
	 * Gets the instance of the used {@link LyciaParser}
	 * 
	 * @return actual XmlParser instance
	 */
	LyciaParser<B> getXmlParser();

	/**
	 * This method is called whenever {@link LyciaParser} is ready to read some
	 * file of structured data into an DOM. The actual implementation behind
	 * this interface method has to read data from datasource and transform them
	 * to an Xml alike DOM representation that is returned.
	 * 
	 * @param inputSource
	 *            The input data
	 * @return DOM representation of the structured data
	 * @throws Exception
	 *             Possibly throws exceptionsF
	 */
	Document read(InputSource inputSource) throws Exception;
}
